<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic
  PUBLIC "-//OASIS//DTD DITA Composite//EN" "ditabase.dtd">
<topic id="topic1">
    <title id="jx138388">gpssh</title>
    <body>
        <p>Provides SSH access to multiple hosts at once.</p>
        <section id="section2">
            <title>Synopsis</title>
            <codeblock>gpssh { -f &lt;hostfile_gpssh> | - h &lt;hostname> [-h &lt;hostname> ...] } <ph>[-s] </ph>[-e]
      [-d &lt;seconds>] [-t &lt;multiplier>] [-v]
      [&lt;bash_command>]

gpssh -? 

gpssh --version</codeblock>
        </section>
        <section id="section3"><title>Description</title><p>The <codeph>gpssh</codeph> utility
                allows you to run bash shell commands on multiple hosts at once using SSH (secure
                shell). You can run a single command by specifying it on the command-line, or omit
                the command to enter into an interactive command-line session. </p><p>To specify the
                hosts involved in the SSH session, use the <codeph>-f</codeph> option to specify a
                file containing a list of host names, or use the <codeph>-h</codeph> option to name
                single host names on the command-line. At least one host name (<codeph>-h</codeph>)
                or a host file (<codeph>-f</codeph>) is required. Note that the current host is
                        <b><i>not</i></b> included in the session by default — to include the local
                host, you must explicitly declare it in the list of hosts involved in the
                session.</p><ph/><p>Before using <codeph>gpssh</codeph>, you must have a trusted
                host setup between the hosts involved in the SSH session. You can use the utility
                    <codeph>gpssh-exkeys</codeph> to update the known host files and exchange public
                keys between hosts if you have not done so already.</p><p>If you do not specify a
                command on the command-line, <codeph>gpssh</codeph> will go into interactive mode.
                At the <codeph>gpssh</codeph> command prompt (<codeph>=&gt;</codeph>), you can enter
                a command as you would in a regular bash terminal command-line, and the command will
                be run on all hosts involved in the session. To end an interactive session, press
                    <codeph>CTRL</codeph>+<codeph>D</codeph> on the keyboard or type
                    <codeph>exit</codeph> or <codeph>quit</codeph>.</p><p>If a user name is not
                specified in the host file, <codeph>gpssh</codeph> will run commands as the
                currently logged in user. To determine the currently logged in user, do a
                    <codeph>whoami</codeph> command. By default, <codeph>gpssh</codeph> goes to
                    <codeph>$HOME</codeph> of the session user on the remote hosts after login. To
                ensure commands are run correctly on all remote hosts, you should always enter
                absolute paths.</p><p>If you encounter network timeout problems when using
                    <codeph>gpssh</codeph>, you can use <codeph>-d</codeph> and <codeph>-t</codeph>
                options or set parameters in the <codeph>gpssh.conf</codeph> file to control the
                timing that <codeph>gpssh</codeph> uses when validating the initial
                    <codeph>ssh</codeph> connection. For information about the configuration file,
                see <xref href="#topic1/section6" format="dita"/>.</p></section>
        <section id="section4">
            <title>Options</title>
            <parml>
                <plentry>
                    <pt>
                        <varname>bash_command</varname>
                    </pt>
                    <pd>A bash shell command to run on all hosts involved in this session
                        (optionally enclosed in quotes). If not specified, <codeph>gpssh</codeph>
                        starts an interactive session.</pd>
                </plentry>
                <plentry>
                    <pt>-d (delay) <varname>seconds</varname></pt>
                    <pd>Optional. Specifies the time, in seconds, to wait at the start of a
                            <codeph>gpssh</codeph> interaction with <codeph>ssh</codeph>. Default is
                            <codeph>0.05</codeph>. This option overrides the
                            <codeph>delaybeforesend</codeph> value that is specified in the
                            <codeph>gpssh.conf</codeph> configuration file.</pd>
                    <pd>Increasing this value can cause a long wait time during
                            <codeph>gpssh</codeph> startup. </pd>
                </plentry>
                <plentry>
                    <pt>-e (echo)</pt>
                    <pd>Optional. Echoes the commands passed to each host and their resulting output
                        while running in non-interactive mode.</pd>
                </plentry>
                <plentry>
                    <pt>-f <varname>hostfile_gpssh</varname></pt>
                    <pd>Specifies the name of a file that contains a list of hosts that will
                        participate in this SSH session. The syntax of the host file is one host
                        per line.</pd>
                </plentry>
                <plentry>
                    <pt>-h <varname>hostname</varname></pt>
                    <pd>Specifies a single host name that will participate in this SSH session. You
                        can use the <codeph>-h</codeph> option multiple times to specify multiple
                        host names.</pd>
                </plentry>
                <plentry>
                    <pt>-s</pt>
                    <pd>Optional. If specified, before running any commands on the target host,
                            <codeph>gpssh</codeph> sources the file
                            <codeph>greenplum_path.sh</codeph> in the directory specified by the
                            <codeph>$GPHOME</codeph> environment variable. </pd>
                    <pd>This option is valid for both interactive mode and single command mode.</pd>
                </plentry>
                <plentry>
                    <pt>-t <varname>multiplier</varname>
                    </pt>
                    <pd>Optional. A decimal number greater than 0 (zero) that is the multiplier for
                        the timeout that <codeph>gpssh</codeph> uses when validating the
                            <codeph>ssh</codeph> prompt. Default is <codeph>1</codeph>. This option
                        overrides the <codeph>prompt_validation_timeout</codeph> value that is
                        specified in the <codeph>gpssh.conf</codeph> configuration file.</pd>
                    <pd>Increasing this value has a small impact during <codeph>gpssh</codeph>
                        startup. </pd>
                </plentry>
                <plentry>
                    <pt>-v (verbose mode)</pt>
                    <pd>Optional. Reports additional messages in addition to the command output when
                        running in non-interactive mode.</pd>
                </plentry>
                <plentry>
                    <pt>--version</pt>
                    <pd>Displays the version of this utility.</pd>
                </plentry>
                <plentry>
                    <pt>-? (help)</pt>
                    <pd>Displays the online help.</pd>
                </plentry>
            </parml>
        </section>
        <section id="section6">
            <title>gpssh Configuration File</title>
            <p>The <codeph>gpssh.conf</codeph> file contains parameters that let you adjust the
                timing that <codeph>gpssh</codeph> uses when validating the initial
                    <codeph>ssh</codeph> connection. These parameters affect the network connection
                before the <codeph>gpssh</codeph> session runs commands with
                    <codeph>ssh</codeph>. The location of the file is specified by the environment
                variable <codeph>MASTER_DATA_DIRECTORY</codeph>. If the environment variable is not
                defined or the <codeph>gpssh.conf</codeph> file does not exist,
                    <codeph>gpssh</codeph> uses the default values or the values set with the
                    <codeph>-d</codeph> and <codeph>-t</codeph> options. For information about the
                environment variable, see the <cite>Greenplum Database Reference Guide</cite>. </p>
            <p>The <codeph>gpssh.conf</codeph> file is a text file that consists of a
                    <codeph>[gpssh]</codeph> section and parameters. On a line, the
                    <codeph>#</codeph> (pound sign) indicates the start of a comment. This is an
                example <codeph>gpssh.conf</codeph> file.</p>
            <codeblock>[gpssh]
delaybeforesend = 0.05
prompt_validation_timeout = 1.0
sync_retries = 5</codeblock>
            <p>These are the <codeph>gpssh.conf</codeph> parameters.</p>
            <parml>
                <plentry>
                    <pt>delaybeforesend = <varname>seconds</varname></pt>
                    <pd>Specifies the time, in seconds, to wait at the start of a
                            <codeph>gpssh</codeph> interaction with <codeph>ssh</codeph>. Default is
                        0.05. Increasing this value can cause a long wait time during
                            <codeph>gpssh</codeph> startup. The <codeph>-d</codeph> option overrides
                        this parameter.</pd>
                </plentry>
                <plentry>
                    <pt>prompt_validation_timeout = <varname>multiplier</varname></pt>
                    <pd>A decimal number greater than 0 (zero) that is the multiplier for the
                        timeout that <codeph>gpssh</codeph> uses when validating the
                            <codeph>ssh</codeph> prompt. Increasing this value has a small impact
                        during <codeph>gpssh</codeph> startup. Default is <codeph>1</codeph>. The
                            <codeph>-t</codeph> option overrides this parameter.</pd>
                </plentry>
                <plentry>
                    <pt>sync_retries = <varname>attempts</varname></pt>
                    <pd>A non-negative integer that specifies the maximum number of times that
                            <codeph>gpssh</codeph> attempts to connect to a remote Greenplum
                        Database host. The default is 3. If the value is 0, <codeph>gpssh</codeph>
                        returns an error if the initial connection attempt fails. Increasing the
                        number of attempts also increases the time between retry attempts. This
                        parameter cannot be configured with a command-line option. </pd>
                    <pd>The <codeph>-t</codeph> option also affects the time between retry
                        attempts.</pd>
                    <pd>Increasing this value can compensate for slow network performance or segment
                        host performance issues such as heavy CPU or I/O load. However, when a
                        connection cannot be established, an increased value also increases the
                        delay when an error is returned.</pd>
                </plentry>
            </parml>
        </section>
        <section id="section5">
            <title>Examples</title>
            <p>Start an interactive group SSH session with all hosts listed in the file
                    <codeph>hostfile_gpssh</codeph>:</p>
            <codeblock>$ gpssh -f hostfile_gpssh</codeblock>
            <p>At the <codeph>gpssh</codeph> interactive command prompt, run a shell command on all
                the hosts involved in this session.</p>
            <codeblock>=&gt; ls -a /data/primary/*</codeblock>
            <p>Exit an interactive session:</p>
            <codeblock>=&gt; exit
=&gt; quit</codeblock>
            <p>Start a non-interactive group SSH session with the hosts named <codeph>sdw1</codeph>
                and <codeph>sdw2</codeph> and pass a file containing several commands named
                    <codeph>command_file</codeph> to <codeph>gpssh</codeph>:</p>
            <codeblock>$ gpssh -h sdw1 -h sdw2 -v -e &lt; command_file</codeblock>
            <p>Run single commands in non-interactive mode on hosts <codeph>sdw2</codeph> and
                    <codeph>localhost</codeph>:</p>
            <codeblock>$ gpssh -h sdw2 -h localhost -v -e 'ls -a /data/primary/*'
$ gpssh -h sdw2 -h localhost -v -e 'echo $GPHOME'
$ gpssh -h sdw2 -h localhost -v -e 'ls -1 | wc -l'</codeblock>
        </section>
        <section>
            <title>See Also</title>
            <p><xref href="gpssh-exkeys.xml#topic1"/>, <xref href="gpscp.xml#topic1"/></p>
        </section>
    </body>
</topic>
